* This feature requires the Advanced Scripting License
<a name="BASICFLC"><h1>Basic Flow Control</h1>
The basic flow control commands, (such as If, Begin, End, Again, Stop), let you control the order in which the lines of your script are executed. You can, for example, execute a block of commands only under certain circumstances, or cause a group of commands to be executed repeatedly ("looping").
<a name="AGAINCOM"><h2>Again</h2>
Format Again [v1 k2 v3]
Examples See the <a href="#BEGINCOM">Begin</a> command
Purpose Causes a <a href="#BEGINCOM">Begin</a> block to repeat if the comparison is true (or if
no comparison is specified)
Parameters v1 - Value to be compared
k2 - <a href="pommel://Help-Comparators.txt">Comparator</a> (click for details)
v3 - Value to compare to v1
Restrictions You cannot combine an Again command with an If command.
<a name="BEGINCOM"><h2>Begin</h2>
Format Begin [v1 k2 v3]
Example Begin MyVar = 'XYZ' ; Execute block if MyVar equals 'XYZ'
Purpose Marks the start of a conditional block of script code
Parameters v1 - Value to be compared
k2 - <a href="pommel://Help-Comparators.txt">Comparator</a> (click for details)
v3 - Value to compare to v1
Defaults If no comparison is specified, the block always begins. In such
case, it makes no sense to have an <a href="#ELSECOMM">Else</a> command, and it almost
invariably means that the block will end with an <a href="#AGAINCOM">Again</a> command.
Restrictions You cannot combine a Begin command with an If command.
Similar Cmds If
Notes Comparisons are not case-sensitive, so 'CAT' = 'Cat' (unless
you have altered the CompareCtrl setting).
The Begin command does <b>not</b> set the $Success variable!
Begin blocks can be nested up to 25 levels deep.
Here is an example of the Begin command, used with Else and End:
<hl>
Begin MyVar = 'Cat'
OutEnd 'The animal is feline' ; Executed if MyVar = 'Cat'
OutEnd 'In fact, it is a cat' ; Executed if MyVar = 'Cat'
Else
OutEnd 'The animal is not feline' ; Executed if MyVar is <b>not</b> 'Cat'
End
</hl>
Note the use of indentation. Indentation of the conditional code blocks is not mandatory, but it does make a complicated script much easier to understand. This is particularly important if a Begin block contains other Begin blocks:
<hl>
Begin CustCode[1 3] = 'USA'
OutEnd 'The customer is in the USA'
Begin CustCode[4 5] = 'NY'
OutEnd 'The customer is in New York'
End
Begin CustCode[4 5] = 'TX'
OutEnd 'The customer is in Texas'
End
End
</hl>
Without the indentation, the logic of the code above would be hard to follow.
Here is an example of the Begin command used in a loop:
<hl>
Counter = 0
Begin
Counter = Counter+
OutEnd 'The counter equals ' Counter
Again Counter #< 10
</hl>
This would output the numbers from 1 to 10. You could also do it this way:
<hl>
Counter = 0
Begin Counter #< 10
Counter = Counter+
OutEnd 'The counter equals ' Counter
Again
</hl>
This would output the numbers from 1 to 10.
If you wish, you can put comparisons on both the Begin and Again. Both tests are repeated on every iteration of the loop.
<a name="BREAKCOM"><h2>Break</h2>
Format Break
Example If CustNum = MaxCustNum Break
Purpose Breaks out of the current Begin/Again block, carrying on
execution at the line following the next Again command
Similar Cmds Continue
<a name="CALLCOMM"><h2>Call</h2>
Format Call v1 [v2 v3 v4...]
Example Call MyProcedure 'Hello!' ; Pass 'Hello!' to MyProcedure
Purpose Invoke a generalized section of script code
Parameters v1 - The name of the <a href="#PROCEDUR">Procedure</a>; doubles as a variable for
passing information to and receiving results back from
the Procedure
v2 - Value (any number of values can be appended)
Defaults If v2 is not specified, the procedure variable v1 is assigned
a null value.
Restrictions Calls from procedures into other procedures, which in turn call
other procedures (and so on), can nest up to 50 levels deep.
When you Call a procedure, execution of the script jumps to the first line of the procedure and continues until the corresponding End statement. The name of the procedure is also the variable name containing any parameters passed in v2, v3 and so on (the values are concatenated). Here is a sample script:
<hl>
Call OutWithExclaim 'Hello, ' ' world' ; Call the procedure
OutEnd 'Glad you could join us!' ; This line is run after the Call
Stop ; Stop running script lines
Procedure OutWithExclaim ; Start of the procedure
OutWithExclaim = OutWithExclaim '!' ; Add an exclamation point
OutEnd OutWithExclaim ; Output
End ; Return to the line after the Call
</hl>
This would output the string 'Hello, world!' then return to the line following the Call command.
<a name="CONTINUE"><h2>Continue</h2>
Format Continue
Example If Status = 'Ignore' Continue
Purpose Jumps ahead to the Again of the current Begin/Again block
Similar Cmds Break
<a name="DONECOMM"><h2>Done</h2>
Format Done
Purpose Skips the rest of the script (for the current record)
Similar Cmds Stop, NextStep
Notes The Done command is usually used with the <b><a href="#IFCOMMAN">If</a></b> command,
or at the end of a Begin/End block.
<a name="ELSECOMM"><h2>Else</h2>
Format Else
Example See the <a href="#BEGINCOM">Begin</a> command
Purpose Defines the start of the conditional code block that is
executed if the <a href="#BEGINCOM">Begin</a> comparison is false.
Restrictions You cannot combine an Else command with an If command.
<a name="ENDCOMMA"><h2>End</h2>
Format End
Examples See the <a href="#BEGINCOM">Begin</a> command
Purpose Marks the end of a <a href="#BEGINCOM">Begin</a> block
Restrictions You cannot combine an End command with an If command.
<a name="EXITCOMM"><h2>Exit</h2>
Format Exit
Purpose Immediately returns from a Procedure
Restrictions The Exit command can only be used inside a <a href="#PROCEDUR">Procedure</a>.
Notes The Exit command is typically used in conjunction with a
comparison. You do <b>not</b> need to include an Exit command
in every Procedure.
<a name="IFCOMMAN"><h2>If</h2>
Format If v1 k2 v3 c4
Examples If CustCode = 'AB12' OutEnd 'Mary Smith'
If CustCode = 'CD34' CustAddr = '1234 Happy Lane'
Purpose Conditionally performs a command
Parameters v1 - Value to be compared
k2 - <a href="pommel://Help-Comparators.txt">Comparator</a> (click for details)
v3 - Value to compare to v1
c4 - Command
Restrictions The If command may not be combined with a command that defines
the start of a code block, such as Begin or FileInit.
Similar Cmds Begin, End, Again
Notes The comparison is case-insensitive, so 'CAT' = 'cat' unless
you have altered the CompareCtrl setting.
The If command does <b>not</b> set the $Success variable!
In deference to the ingrained training of seasoned programmers, you may use the word "then" after the comparison. Thus, the following command will be accepted:
<hl>
If x > y then z = 'Hello'
</hl>
This usage is non-standard, however, and is not recommended. The scripting engine treats the "then" as a variable, but ignores it in this context. Thus, you should never use a variable named "Then".
The If command does not have an "Else" option as in most programming languages. To execute a command when the If condition is false, use the <a href="#OTHERWIS">Otherwise</a> command. Alternatively, you can use the Begin command with an Else section.
<a name="OTHERWIS"><h2>Otherwise</h2>
Format Otherwise c1
Example If Animal = 'Cat' Type = 'Feline' ; The initial If command
Otherwise Type = 'Non-feline' ; Action taken if false
Purpose Executes an alternative command when the If comparison is false
Parameters c1 - Command
Restrictions The Otherwise command must follow immediately after an If.
The Otherwise command may not be combined with a command that
defines the start of a code block, such as Begin or FileInit.
Similar Cmds Else
<a name="PROCEDUR"><h2>Procedure</h2>
Format Procedure v1
Example Procedure MyCode
Purpose Defines the start of a generalized section of script code, which
is terminated with the End command
Parameters v1 - The name of the Procedure (must be a simple variable)
Restrictions Recursive procedures (i.e. procedures that call themselves) are
not formally supported and their use is not recommended.
Notes See the <a href="#CALLCOMM">Call</a> command for a full discussion of procedures.
As the script is being run, any Procedure sections are ignored when encountered; they are only executed when explicitly invoked by <a href="#CALLCOMM">Call</a>. Procedures can go anywhere except within conditional blocks such as Begin/End, FileInit/End and so on. Procedures are usually placed together at the end of the script.
<a name="STOPCOMM"><h2>Stop</h2>
Format Stop [v1]
Example If CustNum[1] = 'X' Stop 'Invalid customer number'
Purpose Terminates further processing
Parameters v1 - Optional pop-up message
Similar Cmds Done, NextStep
Notes If v1 is included, a pop-up message is displayed. In such case,
the Stop is considered an "abnormal" end of processing and the
script-enabled application should proceed accordingly.
<a name="STEPCONT"><h1>Step Control</h1>
A simple script runs from top to bottom each time a record is sent to it. But how can you initialize variables before processing starts? How can you output a grand total after all the records have been processed?
These issues and others are addressed by the step control commands.
When processing files, Parse-O-Matic performs a series of steps:
<hl>
TaskInit Executes before data is read from the <b>first</b> input file
FileInit Executes before data is read from the <b>current</b> input file
Main Executes once for each record sent to the script
FileDone Executes after the last data is read from the <b>current</b> input file
TaskDone Executes after the last data is read from the <b>last</b> input file
</hl>
If you are only processing a single file (i.e. you are not using wildcards to process multiple input files), there is little to distinguish TaskInit and TaskDone from FileInit and FileDone.
Except for the Main step, each step appears inside a conditional block, as in this example:
<hl>
TaskInit ; Start of the TaskInit step
OutEnd 'Customer Count Report' ; Report header
OutEnd '---------------------' ; Report header
End ; End of the TaskInit step
FileInit ; Start of the FileInit step
OutEnd 'Input file: ' $ActualIFN ; Output the file name
NumInpFiles = NumInpFiles+ ; Count this input file
End ; End of the FileInit step
CustCount = CustCount+ ; Main step: count record
TaskDone ; Start of the TaskDone step
OutNull ; Output a blank line
OutEnd 'Number of input files: ' NumInpFiles ; Output statistics
OutEnd 'Number of customers: ' CustCount ; Output statistics
End ; End of the TaskDone step
</hl>
In the example given above, the conditional code for the report header was placed in TaskInit so that the script will output it only once, even if you are processing multiple input files.
The conditional steps are optional. For example, you do not have to include FileInit in your script.
The conditional steps can appear almost anywhere in your script (though not within another conditional block).
<a name="FILEINIT"><h2>FileInit and FileDone</h2>
The FileInit section is executed before each input file is processed. The FileDone section is executed after each input file is processed. For details, click <a href="#STEPCONT">here</a>.
You cannot combine the FileInit or FileDone commands with the If command.
<a name="TASKINIT"><h2>TaskInit and TaskDone</h2>
The TaskInit section is executed before data is read from the first input file. The TaskDone section is executed after the last record is read from the last input file. For additional details, click <a href="#STEPCONT">here</a>.
You cannot combine the TaskInit or TaskDone commands with the If command.
<a name="NEXTSTEP"><h2>NextStep</h2>
The NextStep command can be used to jump out of a <a href="#STEPCONT">step</a> (such as FileInit or Main) and proceed to the next step.
For example, if your Main step has already located the information you are seeking, there is no reason to continue reading the input file. In such case, you can execute a NextStep command to ignore the rest of the input file and proceed immediately to FileDone, as in the following example.
<hl>
CustNum = $OutData[1 6] ; Main step: Get customer number
PhoneNum = $OutData[60 70] ; Main step: Get the phone number
If CustNum = '314159' NextStep ; Main step: Found the customer?
FileDone ; Start of the FileDone step
OutEnd 'Phone Number = ' PhoneNum ; Output the information we sought
End ; End of the FileDone step
</hl>
NextStep should not be confused with the <a href="#STOPCOMM">Stop</a> command, which causes processing to cease entirely.
NextStep is also different from <a href="#DONECOMM">Done</a>, which skips the rest of the script and then (if used in the Main step) proceeds to process the next record from the input file. The Done command can, however, be used within a conditional step block (such as FileInit) to skip the rest of that step; in such case it will behave the same way as NextStep.
